Kernel compilation and update

Copyright © Quectel Wireless Solutions Co., Ltd. 2026. All rights reserved.

---

Overview

This document describes the complete process of compiling the Linux kernel for Quectel Pi H1, packaging kernel images, and updating them to the device. Quectel Pi H1 uses a Yocto-based build system with a Qualcomm-customized Linux kernel (based on Linux 6.6).

Kernel recipes description

Qualcomm Linux kernel recipes are located in the /layers/meta-qcom-hwe/recipes-kernel/linux directory. This layer provides two kernel solutions:

Recipe File	Kernel Type	Source	Description
linux-qcom-custom_6.6.bb	Custom BSP	git.codelinaro.org	Qualcomm-customized kernel (currently used)
linux-qcom-base_6.6.bb	Base BSP	git.kernel.org	Standard kernel

Currently used: Custom kernel source solution

Directory structure

Kernel-related files are divided into two directories:

qcm6490-idp/
├── kernel-source/               # Kernel source directory
└── kernel-build-artifacts/      # Build artifacts directory

Kernel-source/ Directory

This directory stores the complete source code of the Linux kernel, including:

• Kernel core code (arch/, drivers/, fs/, net/, etc.)

• Device tree source files (.dts/.dtsi, describing hardware configurations)

• Kernel configuration files (Kconfig)

• Build scripts (Makefile)

Source directory details

Directory/File	Description	Directory/File	Description
arch	Architecture-related code (ARM64, x86, etc.)	scripts	Compilation and configuration scripts
block	Block device subsystem	security	Security framework (SELinux, AppArmor, etc.)
certs	Kernel certificates and signatures	sound	Audio subsystem (ALSA)
crypto	Encryption API and algorithms	tools	Kernel-related tools
Documentation	Kernel documentation	usr	initramfs generation related
drivers	Device drivers	virt	Virtualization support (KVM)
fs	File system implementation	rust	Rust language support
include	Kernel header files	Makefile	Main configuration file
init	Kernel initialization code	Kbuild	Kernel build system configuration
ipc	Inter-process communication mechanisms	Kconfig	Kernel configuration interface definition
kernel	Kernel core functionalities (scheduler, process management, etc.)	MAINTAINERS	Maintainer list
lib	Common library functions	CREDITS	Contributor list
mm	Memory management subsystem	COPYING	Copyright notice (GPL)
net	Network protocol stack
samples	Kernel programming example code

Kernel-build-artifacts/ Directory

This directory stores kernel build artifacts after compilation, including:

• Kernel image files: Image (uncompressed) or Image.gz (compressed version)

• Device tree binary files: .dtb files (compiled from .dts)

• Kernel modules: .ko files (loadable driver modules)

• Configuration files: .config, build.log, etc.

Compile kernel

Configure build environment

Enter the code working directory and execute the following command to configure the build environment:

source quectel_build/compile/build.sh

Execute compilation

Use Yocto’s bitbake command to compile the kernel:

bitbake linux-qcom-custom

Build artifact paths

After compilation is complete, the kernel image is generated at the following location:

Temporary working directory:

build-qcom-wayland/tmp-glibc/work/qcm6490_idp-qcom-linux/linux-qcom-custom/6.6/deploy-linux-qcom-custom

Final deployment directory (automatically copied by Yocto):

build-qcom-wayland/tmp-glibc/deploy/images/qcm6490-idp/

Note: Yocto will automatically copy the kernel image from the working directory to the deployment directory. During the subsequent packaging process, the kernel image is obtained from the deployment directory.

Build time reference

• First build: Approximately 30–60 minutes (depending on hardware configurations)

• Incremental build: Approximately 5–15 minutes

Package kernel and device tree images

Install ukify tool

First, install the Python dependencies required for packaging:

sudo pip install pefile

Execute packaging command

Run the following command to package the kernel image and device tree:

do_kernel_images

ukify warning description

During the packaging process, the following warning messages will appear, which can be ignored:

Kernel version not specified, starting autodetection .
Real-Mode Kernel Header magic not found
+ readelf --notes {TOPDIR}/quectel_build/alpha/tools/pack/image_temp/Image
readelf: Error: Not an ELF file - it has the wrong magic bytes at the start
Found uname version: 6.6.52-qli-1.3-ver.1.1
Wrote unsigned ${TOPDIR}/quectel_build/alpha/tools/pack/image_temp/uki.efi

Note: These warnings are caused by differences between ARM64 kernel format and EFI tool expected format, and do not affect the correctness of the final image.

Get packaged image

After packaging is complete, obtain the generated image file from the following path:

${TOPDIR}/quectel_build/alpha/output/pack/efi.bin

Update image to device

Method 1: Enter Fastboot via debug UART

Enter Fastboot mode

Option A - Via serial port command:

Connect the debug UART and execute in the system:

reboot bootloader

Option B - Via ADB command:

Ensure the device is connected via USB and ADB debugging is enabled, then execute:

adb shell
reboot bootloader

Verify Fastboot mode

After the device enters Fastboot mode, run on the host:

fastboot devices

Now you can see the device list.

Flash kernel image

Use the fastboot command to flash the new kernel image:

fastboot flash efi efi.bin

Reboot device

After flashing is complete, reboot the device:

fastboot reboot

Method 2: Automation script (optional)

If you need to frequently update the kernel, you can create an automation script:

#!/bin/bash# update_kernel.sh# Check if efi.bin existsif [ ! -f "quectel_build/alpha/output/pack/efi.bin" ]; thenecho "Error: efi.bin does not exist, please compile and package the kernel first."exit 1fi# Enter Fastboot
adb reboot bootloader
sleep 5# Wait for Fastboot to be ready
fastboot devices

# Flash image
fastboot flash efi quectel_build/alpha/output/pack/efi.bin

# Reboot
fastboot rebootecho "Kernel update complete!"

Usage:

chmod +x update_kernel.sh
./update_kernel.sh

Notes

1. Backup important data: Before updating the kernel, ensure important data is backed up.

2. Sufficient power: Ensure the device has sufficient power or is connected to power during flashing.

3. Stable USB connection: Use a good quality USB cable to avoid flashing interruption.

4. Version matching: Ensure the kernel version is compatible with other system components.

FAQs

Q1: bitbake compilation failed?

Possible causes:

• Insufficient disk space

• Network connection problems

• Missing dependency packages

Solution:

# Clean build cache
bitbake -c cleanall linux-qcom-custom
# Recompile
bitbake linux-qcom-custom

Q2: Device cannot be seen after Fastboot mode is verified?

Solution:

• Check if USB drivers are correctly installed

• Try changing USB port or cable

• Confirm the device has correctly entered Fastboot mode (screen displays Fastboot text)

Q3: Cannot boot after flashing?

Solution:

• Use factory image to restore the system

• Check if there were errors during compilation

• Confirm device tree configuration is correct

Related documents

• Device tree file description

• Cross-Compilation toolchain